GifBuilder is a scriptable utility for creating animated GIF files. Its input is an existing animated GIF, a bunch of PICT, GIF and/or TIFF files or a QuickTime movie, and its output is a GIF89a file with multiple images.
Options include pixel depth, color palette, interlacing, transparency, interframe delay, disposal method, frame offset, looping and dithering.
GifBuilder should ultimately be placed onto many ftp archives, including Info-Mac (in gst/grf), Umich (in graphics/graphicsutil) and their mirrors.
Please read this document carefully if you want to get the best of GifBuilder. There are several shortcuts which can make your work much easier.
Usage
1) Draw each frame
Use any drawing program able to save as PICT, GIF or TIFF. Save frames in a new folder to make their retrieval easier. If you name them in alphabetical order (e.g. 0001.tiff, 0002.tiff, etc.), you can easily sort them later.
2) Collect frames in GifBuilder
Launch GifBuilder, be sure that there aren't frames from a previous animation in the Frames window (if that's the case, choose New in the File menu), and drag the frames from the Finder into the Frames window. If you don't have the Drag Manager (standard since MacOS 7.5), you can add each frame by choosing Add Frame in the File menu. You can also copy a picture from another application. Then, check that they're in the correct order and, if necessary, change their order by dragging frames. You can also remove the selected frame(s) by choosing Clear in the Edit menu or hitting Backspace, sort them and reverse their order. Double-clicking a frame will open it in its own application; if you modify it, save it and choose Reload Frames in the File menu to update your changes (the Save command always use the disk copy).
3) Set the options
Set the standard graphic options (pixel depth, color palette and dithering); the GIF options (size, interlacing, transparency); and the animation options (interframe delay, disposal method, frames position and looping). Some of these properties (transparency, interframe delay, disposal method and position) are attached to individual frames; select the frame or group of frames before changing them. If no frame is selected, the settings will apply to the first image you import. Other images get their properties from the preceeding frame. If you set a transparent mode and the transparent region moves, you should probably not use Do Not Dispose, because there would be a trail effect. The Loop option is used by NetScape Navigator 2.0 and later (hopefully); it causes the animation to repeat endlessly. The global size can be set to include all the frames or to a fixed value; if necessary, frames are cropped to fit. You can save the default options by choosing Save Options in the Options menu.
Tip: Most options displayed in the Frames window can be changed by clicking or double-clicking them.
4) Check the animation
Choose Run in the Animation menu. To display a specific frame, stop the animation and select it in the Frames window. You can also use the Home, End, Up and Down keys. To start from the first selected frame, choose Continue. In the Animation window, you can move a frame by dragging it, or select the transparent color by Shift-clicking it (you can do it even when the animation is running, but depending on the speed, you'd better stop it first!).
5) Build the animation
Choose Save As in the File menu.
6) Add an image tag to your HTML page
Choose Copy HTML Image Tag in the Edit menu, and paste the resulting IMG tag in your HTML page. IMG fields contain a relative URL with the current name of the animation as well as the width and height. Of course, you can edit the tag to change the path of the image or add optional fields like ALT and ALIGN.
Options
Interlaced: With interlacing, a first rough image is loaded first, and then the vertical resolution improves in three additional passes. It isn't very useful for animations.
Colors and Depth: For cross-platform web animations, the 6x6x6 color table is recommended. The system (or grayscale) 1 bit/pixel table should be used for black and white images. Images created with other settings are likely to be dithered on color-table-based machines.
Dithering: Dithering is a way to simulate intermediate color shades with clouds of points. It should be used with continuous-tone images. With dithering, the color table should be chosen so that the image isn't dithered a second time on the target machine (see above), and transparency should be off.
Image Size: When Minimum Size is on, the size is calculated so that the animation's bottom right corner corresponds to the rightest lowest frame. Frames are always cropped to fit in the animation bounding box.
Background Color: The Background Color is the color used to paint the animation bounding box where no frame is displayed. With some Web browsers, the page background is used instead.
Loop: The Loop option specifies how many times the animation is repeated. Some browsers don't recognize this option, while others loop an unlimited number of times if the setting is more than 1.
Transparent Background: All pixels wich have the color specified by the Transparent Background are left untouched when the frame is rendered.
Frame Position: Each frame can be shifted by an arbitrary amount. The Frame Position specifies the horizontal and vertical distances between the top left animation corner and the top left frame corner. Positive values push the frame to the left and to the lower part. Negative values result in a cropped frame.
Interframe Delay: The Interframe Delay is the delay between the current frame and the following frame renderings. It's specified in hundredths of seconds (i.e. 100 means 1 second).
Disposal Method: The Disposal Method specifies what each frame becomes once the interframe delay is elapsed. Use Unspecified when transparency is off and each frame covers the whole animation, Do Not Dispose when you want to add some bits of image to the previous animation state, Revert to Background for moving objects on a transparent background, and Revert to Previous for moving objects on a background you've drawn with an earlier large frame. Note that Revert to Background isn't supported by some browsers.
Remarks
New: After asking you if you want to save your previous animation, New removes all the frames and reads the default settings from the Preference file.
Open: You can open an existing animation, or append to the end of the current animation by holding down the Shift key and choosing Open in the File menu or typing Command-Shift-O.
Frames displayed in italic are loaded in memory, while those displayed in roman correspond to separate files.
Convert: You can convert a QuickTime movie directly to an animated GIF without opening it, by choosing Convert in the File menu. This saves a lot of memory.
Clear: Clear (in the Edit menu) or the Backspace key deletes the selected frames. To preserve the timing, hold down the Shift key and choose Special Clear or type Backspace. Example:
Before Clear:
Clear:
Shift-Clear:
Undo: Undo allows to return to the state just before the last operation which changed the frames or frame order.
Color palette: System Palette and Gray Shades are fixed palette. Best Palette is optimized for all the frames simultaneously. Load Palette allows to use a Photoshop-compatible palette file. Such a palette is included with GifBuilder: named "6x6x6 Palette", it's a subset of the System palette where each component takes the six values 0, 51, 102, 153, 204 and 255; it has 6x6x6 = 216 entries. It's the palette used by NetScape for Windows, so you might want to choose it to avoid additional dithering on both Macintosh and Windows machines. You can also use an alternative palette named "16 from 6x6x6 Palette": it's a subset of the previous one, with the eight basic colors (where each component is 0 or 255), plus eight useful other ones: (153,153,153), (0,153,255), (255,51,0), (51,153,0), (255,153,255), (153,204,255), (255,255,153) and (204,204,204) (see below). It should also give good results on both the Mac and Windows.
Note that the 4-bits-per-pixel System palette has some intermediate colors and shouldn't be used if you're concerned about cross-platform issues.
To reuse the color palette of an existing GIF, open the GIF file with Open (in the File menu) and save the palette with Save Palette (in the Colors submenu of the Options menu). The GIF file doesn't have to contain multiple frames.
The format of palette files is 256 entries of three bytes which represent the red, green and blue values of the corresponding index. 0 is black, and 255 is the maximum intensity. For palettes of 16, 4 or 2 entries (corresponding to a depth of 4, 2 or 1 respectively), fill the unused entries with the last entry. The file type is '8BCT', and the file creator should be 'gfBr' (GifBuilder's) to have a nice icon. Note that in AppleScript, RGB values are in the range 0-65535; to convert them from a byte value, multiply them by 257.
When you load a palette, you can't choose the depth anymore. Choose a System, grayscale or best palette before changing the depth.
Scripting
Warning: scripting support is experimental. Some functionality is missing. This should be fixed in future releases.
GifBuilder implements a custom AppleEvent to create an animated GIF file from a bunch of PICT objects:
create GIF:
create GIF picture
in file specification
[color table system colors/gray shades] -- or {{r1,g1,b1},{r2,g2,b2},...}
[depth small integer] -- bits per pixels
[transparency no/white/first pixel] -- or {red,green,blue}
[interlacing boolean]
[disposal method unspecified/no/restore to background/restore to previous]
[interframe delay small integer] -- in 1/100 seconds
[loop boolean]
[dithering boolean]
All the color values are in the range 0 (black) - 65535 (maximum intensity). The PICTs can be created by any good graphic (and many other) applications. Here is an example with clip2gif:
tell application "clip2gif"
set l to {}
save {100, 80} in window
repeat with i from 1 to 20
save {100, 80} in window 1 ¬
drawing {{rectangle:{50 - 2 * i, 40 - i, 50 + 2 * i, 40 + i}, color:{65535, 65535, 0}}, ¬
{drawn text:"Created by clip2gif and GifBuilder", position:{100 - 5 * i, 2, 200 - 5 * i, 30}}, ¬
create GIF l in (new file default name "multigif.gif")
end tell
The core AppleEvents and a rudimentary object model are partially implemented, allowing to create new and modify existing animations. This is the preferred method. Here is an example of what can be done:
tell application "GifBuilder"
open file "animation.gif" -- opens an existing animation
make new frame at the beginning ¬
with data {contents:somePictObject} -- prepends a new frame with default frame options
make new frame at the end ¬
with data {contents:file "lastFrame.tiff",
translation:{10, 10},
transparency:first pixel,
disposal method:restore to background,
interframe delay:50} -- appends another frame, with specified options
make new frame before 5th frame with data {contents:file "newFrame.pict"}
-- inserts a frame
save in file "animation2.gif" -- saves the animation in a new file
end tell
And here is a "real" example that creates a bouncing ball on a transparent black background with clip2gif:
property w : 10
property h : 95
tell application "GifBuilder"
new
repeat with t from -13 to 12
set y to t * t / 2
tell application "clip2gif-ppc" to set p to save {w, h} in picture
drawing {{rectangle:{0, 0, w, h}}, {disk:{0, y, w, y + w}, color:{65535, 0, 0}}}
make new frame at end
with data {contents:p, transparency:first pixel, disposal method:restore to background}
end repeat
set loop to 0
save in new file
run animation
end tell
Results
Some option combinations can give unexpected results; this may be caused by strange features, viewer bugs, or GifBuilder bugs. If you don't succeed in creating files that load correctly in NetScape, choose Reset to Factory Settings in the Options menu and import your frames again.
One of the main goals of GifBuilder is to stick as closely as possible to the GIF 89a specifications, not to reproduce the way animations are performed on some particular browser.
Requirements
GifBuilder requires System 7 or above and 32-bit Color Quickdraw. The Drag Manager (which comes with PowerTalk and System 7.5) is recommended. AppleScript is obviously needed to Apple-script GifBuilder. On the PowerMacs, the file ObjectSupportLib is needed in the Extensions folder; it should be included with the System and AppleScript installer. QuickTime is needed for importing QuickTime movie. If Convert (in the File menu) is dimmed, QuickTime is not correctly installed.
The animation, as well as the individual frames if they're loaded, must fit in RAM; set the application memory partition appropriately (Get Info in the Finder). GifBuilder shouldn't crash in low memory conditions; but if it does, try to increase the memory partition to some high value (if you can) before sending me a bug report.
Frequently Asked Questions
About Animated GIF
Local animations are ok, but when I use an HTTP server, they don't loop and the end of the last frame is corrupted. What happens?
You probably corrupted the file when you uploaded it to the server. Be sure that you choose the binary mode (not MacBinary) for your file transfer.
Can I choose which frame is displayed by old browsers?
No. Some GIF decoders display only the first frame, while others render all the images but don't recognize the looping NetScape 2.0 extension.
Should I put the original images on my server?
No. Animated GIFs are completely self-contained. They don't contain any references to the original files.
How can I stop animations in NetScape 2.0 for the Mac?
You should hold down the Command key and hit the dot key exactly when NetScape reloads the image from its cache.
About GifBuilder
How can I choose the comment displayed by JPEGView and other utilities?
You can't. GifBuilder adds a fixed comment containing its and my names. This is deliberate.
I've found a GifBuilder bug! Revert to Previous doesn't work!
If your browser doesn't handle correctly a feature, this isn't necessarily a GifBuilder bug. This one, for instance, is most probably not.
Images are dithered even if I don't select it in GifBuilder! Why?
Images are usually dithered by the browser if its palette isn't the same as the GIF's. You'd better use the 6x6x6 palette provided with GifBuilder, which is used by several browsers on the Mac as well as on alien machines, and let GifBuilder do the dithering if you need to.
I don't use Windows 3.1 anymore. Are you working on a Windows NT version?
GifBuilder runs on the Mac. I don't intend to port it to any currently available operating system (I might have ideas about new ones, however).
So give me the source, I'll port it.
First, I don't make the source code available. Second, even if it was, the GIF part is about 10% of the whole program. The remaining is closely tied to the Mac user interface and graphical model.
Small Print
This document is Copyright 1995-1996, Yves Piguet. All rights reserved.
The author makes no warranty with respect to this document, its quality, accuracy, or fitness for a particular purpose. As a result, this document is provided "as is", and the user is assuming the entire risk as to its quality and accuracy.
